home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / Libraries / File Dropper 2.0ß1 / Read Me - File Dropper < prev   
Text File  |  1996-06-04  |  14KB  |  300 lines
  1.                                     File Dropper 2.0ß1
  2.                                     Written by Troy Anderson
  3.  
  4.                     Copyright © 1996, Troy Anderson; All Rights Reserved
  5.  
  6.                                     What Is This Thing?
  7.  
  8. File Dropper is a CodeWarrior library that implements an application that you can drop files or 
  9. folders onto to do batch operations on.  It handles the getting of the AppleEvents, the main
  10. event loop, and the menus.  You need only write the code that acts on the individual files.
  11.  
  12. It is WorkWare - I truely believe that if you use this to implement a file handling utility, 
  13. you will save time - probably on the order of days, all things considered.  I ask that you
  14. send me one hour's pay, or US$50 (whichever is greater :) if you use this library and it saves
  15. you time.  My address is:  I sincerely appreciate it.
  16.  
  17. US Mail:        Troy Anderson
  18.                 Concrete Software, Inc.
  19.                 8777 N Gainey Center Drive
  20.                 Suite 236
  21.                 Scottsdale, AZ  85258
  22.  
  23.  
  24.                                     New Features in 2.0ß1
  25.  
  26. • Updated the code to CodeWarrior and to support both 68K and PPC native applications.
  27. • Added CW project stationery so creating new File Dropper based application is painless.
  28. • Removed support for pre-System 7 computers - sorry.
  29.  
  30.                                     New Features in 1.1ß4
  31.  
  32. • Changed the "legal" mumbo-jumbo.
  33.  
  34.                                     New Features in 1.1ß3
  35.                                     
  36. • Fixed a bug so that when you drop a folder onto your File Dropper application, all the files
  37.   inside are processed in stead of just the first one.
  38.   
  39.  
  40.                                     New Features in 1.1ß2
  41.                                     
  42. • Built "File Dropper π" in THINK C 6.0
  43. • The cursor is NOT reset to an arrow after each call to SetStatusPercentage.
  44. • If you return FALSE from the eStartup, eSFInitialize, or eAEInitialize messages, File Dropper 
  45.   will send you an eQuitting message and quit the application.
  46. • If you return FALSE from the eValidate message, File Dropper will skip any remaining files
  47.   in the current batch.
  48. • If you return FALSE from an eDispose message, File Dropper will send you an eQuitting message
  49.   and quit the application.  Returning TRUE from an eDispose message will cause File Dropper to
  50.   continue running.  This behavior does NOT depend upon which of eSFInitialize or eAEInitialize
  51.   was sent to you.
  52. • If you return TRUE from an eQuitting message, the File Dropper quits.  On the other hand, if 
  53.   you return FALSE from an eQuitting message, File Dropper will quit.
  54. • If you want the source code to File Dropper, send me money (see the end of this document).
  55. • Added an eUserCancelled message for when the user clicks Cancel in the status box.
  56. • Added an eIdle message.
  57. • Added the ChangeStatusMessage function that lets you change the message in the status dialog
  58.   on the fly, during your processing of the file.
  59. • Changed some things internally, so you can NOT call InstallCustomGetFSSpecFunc,
  60.   InstallCustomFileFilterFunc, or InstallCustomDialogHookFunc from an eSFInitialize or 
  61.   eAEInitialize message any more, just from eStartup.
  62. • Fixed a bug in the ErrorAlert function so that text relating to the error as well as the
  63.   word "Error." show up in the dialog.
  64. • Made it simpler to support AboutBox functionality.  You just put text in STR# resource 129, and
  65.   it will be displayed in the warp stars.  To enable this feature, return TRUE from the 
  66.   eDoAboutBox message.
  67.                                     
  68.                                     
  69.                                     New Features in 1.1ß1
  70.                                     
  71. • Now you can specify if you want the status dialog displayed while you are working on the files,
  72.   wether they were selected with SFGetFile or an AppleEvent.
  73. • There is a progress bar like Finder 7's that you update by specifying how far along you are with
  74.   a percentage (0 - 100).  You can elect to turn this option off, too.
  75.  
  76.     
  77.                                     How Do I Implement My Part?
  78.  
  79. All definitions and prototypes that you need are in the "FD Interface.h" file.  You simply write
  80. the ModuleMain function, and let the library do the rest.
  81.  
  82. The ModuleMain function takes two parameters, a short and a ModuleDataRec.  The short is a 
  83. message that tells you why you were called.  The ModuleDataRec is a record that contains data 
  84. that you may need in order to perform the required task.  It returns a Boolean value.  The
  85. returned value is ignored in all but one case, when you are sent an eValidateFile message.  See
  86. the eValidateFile message description below for details.
  87.  
  88. Be sure that your project includes the "File Dropper Required Resources" file as well as any
  89. resource file you need.
  90.  
  91. To allow dropping of different types of files/folders/volumes onto your application, change the
  92. 'FREF' resource to include the types of files you can act on.  There are some special types that
  93. correspond to folders, volumes, etc.  For a more indepth discussion of this, see section 9-17 
  94. of Inside Macintosh Volume VI.  See section 9-30 for a list of file types you can use for folders,
  95. floppy disks, the trash, etc.
  96.  
  97. Be sure to change the creator type in the Preferences:68K Project or Preferences:PPC Project
  98. panels, and the creator type in the resource file, and to give your application a cool icon.
  99.  
  100.                                     What Is A ModuleDataRec?
  101.  
  102. The ModuleDataRec is defined as follows:
  103.  
  104. typedef struct 
  105. {
  106.     FSSpec    *theFile;        // a file specification
  107.     long    refcon;            // a reference constant for you to do with what you will
  108. } ModuleDataRec;
  109.  
  110.                                     What Are The Messages?
  111.                                     
  112. There are 6 possible messages, they are eStartup, eAEInitialize, eSFInitialize, 
  113. eValidateFile, eProcessFile, eDispose, and eQuitting.
  114.  
  115. You get the messages in this order:
  116.  
  117. eStartup
  118.     This tells you that the program just started up.  You get this message exactly once.
  119.     In the ModuleDataRec, theFile and refcon are initialize to NULL and 0 respectively.  You
  120.     are free to use refcon for anything you choose, including allocating a handle and saving
  121.     its value in refcon so you can have additional storage.  Nothing really precludes you from
  122.     having global data hanging around, but someday this thing may evolve into a CODE resource
  123.     interface that will make having globals more difficult. I never touch refcon, so what you
  124.     do with it is up to you.
  125.     
  126.     This is a where you should call the customization routines like SetStatusParams,
  127.     InstallCustomGetFSSpecFunc,    InstallCustomFileFilterFunc, or InstallCustomDialogHookFunc.
  128.     Although it's all right to call SetStatusParams from eAEInitialize or eSFInitialize as well.
  129.     
  130.     Return TRUE if everything you did turned out OK (e.g. you got all the memory you asked for).
  131.     Returning FALSE causes File Dropper to send you an eQuitting message and quit.
  132.     
  133. eAEInitialize or eSFInitialize
  134.     This tells you that a file/folder/volume has been selected by the user to be acted upon.
  135.  
  136.     eAEInitialize indicates that the file/folder/volume was "dropped" onto the application or
  137.     sent to it using an 'odoc' AppleEvent.
  138.  
  139.     eSFInitialize indicates that the file (of folder or volume if you've installed a Custom
  140.     GetFSSpec Function using InstallCustomGetFSSpecFunction()) was selected by the user using
  141.     a standard get file dialog.  NOTE: You get this message AFTER the user selects the file.
  142.     If you want to install a custom get file using InstallCustomGetFSSpecFunc,
  143.     InstallCustomFileFilterFunc, or InstallCustomDialogHookFunc, do it in eStartup, not here.
  144.  
  145.     
  146.     It is handy to know wether the file was obtained from a "drop" or from a GetFile dialog
  147.     if, for instance, you have options based on keys pressed when "dropped," but not when 
  148.     obtained from a dialog.
  149.     
  150.     You will receive one of these messages for each batch of files to be processed,
  151.     before you are told to do any processing.
  152.     
  153.     In ModuleDataRec, theFile is meaningless during this message.
  154.     
  155.     Return TRUE if everything you did as a result of this message was OK.
  156.     Returning FALSE causes File Dropper to send you an eQuitting message and quit.
  157.     
  158. eValidateFile
  159.     This asks you if the file specified in the theFile parameter of the ModuleDataRec record
  160.     is valid for you to work on.  I.E. should eProcessFile be sent?  Return TRUE if you want
  161.     to process it, otherwise return FALSE.
  162.     
  163. eProcessFile
  164.     This tells you to do your thing.  You get this message for each file in the batch.  The
  165.     ModuleDataRec will contain a pointer to the FSSpec for the file that you are to process
  166.     in the theFile parameter.
  167.     
  168.     If you return TRUE and there are any more files to process, you will be sent the next
  169.     file in the batch.  If you return FALSE, no more files will be sent to you for the
  170.     current batch.
  171.  
  172. eUserCancelled
  173.     This tells you that the user clicked Cancel in the status dialog while a file was being
  174.     processed.  The ModuleDataRec will contain a pointer to the FSSpec for the file that
  175.     was being processed in the theFile parameter.  Since File Dropper handles the status 
  176.     dialog only when you call SetStatusPercentage, you will get this message while in a
  177.     call to SetStatusPercentage, thus your ModuleMain must be reentrant with respect to the
  178.     eUserCancelled case.
  179.     
  180.     If you return TRUE, you will get an eDispose message, followed by an eQuitting message, 
  181.     then File Dropper will ExitToShell.  Returning FALSE causes File Dropper to act as if 
  182.     the Cancel button was not pressed.  I suggest you always return TRUE unless you have a 
  183.     really good reason not to, like you are keeping track of the fact that the user cancelled
  184.     and will return FALSE from the next eProcessFile.
  185.  
  186. eDispose
  187.     This tells you that the batch is finished.  This balances out the eAEInitialize or 
  188.     eSFInitialize messages.  It gives you a chance to clean up any data structures you
  189.     set up there.
  190.     
  191.     Return FALSE if you want File Dropper to send you an eQuitting message and quit.  
  192.     Return TRUE if you want File Dropper to keep running.
  193.     
  194.     In ModuleDataRec, theFile is meaningless.
  195.  
  196. eQuitting
  197.     This tells you that the application is about to quit.  If you need to save or flush anything,
  198.     this is the time to do it.
  199.     
  200.     The return value is ignored for this call.
  201.     
  202.     In ModuleDataRec, theFile is meaningless.
  203.  
  204. eIdle
  205.     You get one of these for each NULL event File Dropper gets.  You won't get one while you're
  206.     processing a file.
  207.  
  208. eDoAboutBox
  209.     If you return TRUE from this message, I will handle the about box by reading from the STR#
  210.     number 129.  I will read all strings starting with number 1 in that resource and display
  211.     them in the about box.  Only up to about 6 strings will actually fit in the about box. 
  212.     
  213.     If you return FALSE from the eDoAboutBox message, I will assume that you handled the about
  214.     box and do nothing.
  215.     
  216.  
  217. In summary:
  218.  
  219. eStartup
  220.     REPEAT AS LONG AS USER SELECTS THINGS FROM THE GET FILE DIALOG
  221.         eSFInitialize
  222.             REPEAT FOR EACH FILE
  223.                 eValidateFile
  224.                 eProcessFile    (if validation succeeded)
  225.             END REPEAT
  226.         eDispose
  227.         eIdle (until the user selects Open, Quit, or more files get dropped on)
  228.     END REPEAT*
  229. eQuitting
  230.  
  231. * You can make it so that File Dropper quits after the first 
  232.   selection/processing of a file.  See the section on eDispose.
  233.  
  234. -OR-
  235.  
  236. eStartup
  237.     eAEInitialize
  238.         REPEAT FOR EACH FILE
  239.             eValidateFile
  240.             eProcessFile    (if validation succeeded)
  241.         END REPEAT
  242.     eDispose
  243.     eIdle (until the user selects Open, Quit, or more files get dropped on)
  244. eQuitting†
  245.  
  246. † You can make it so that File Dropper stays open until the user actually 
  247.   selects Quit from the File menu or a 'quit' AppleEvent comes in.  See
  248.   the section on eDispose.
  249.  
  250.  
  251.  
  252.                                 About The Guy Who Wrote It
  253.                                     
  254. This was written by me, Troy Anderson, after a comment from a user of Marker that wanted source
  255. so he could do something else with the files that were dropped on the application.  This allows
  256. you to create little utility applications that do fun things.  If you really like this, and you
  257. write software, send me a copy of it.  Thanks.
  258.  
  259. Internet:        troy@concrete.com
  260. America Online: Troy A1
  261. Compuserve:        70410,1407
  262. US Mail:        Troy Anderson
  263.                 8777 N Gainey Center Drive
  264.                 Suite 236
  265.                 Scottsdale, AZ  85258
  266.             
  267.                                 
  268.                                 I Want The Source Code!
  269.                                 
  270. If you want the source code (10 commented source files) including AppleEvent sending and receiving,
  271. handling, file manipulation, PowerPC vs. 68K coding, finder-like status bar, and the warp
  272. stars about box effect, send me a U.S. check for $100 and a self addressed envelope that will hold
  273. a disk or your Compuserve or America Online address or send $90 and your internet address and I'll
  274. send you the latest version of the source code including at least everything mentioned in this
  275. exceedingly long sentence.  See paragraph three in the Legal Stuff section for what you can do
  276. once you have the souce code, besides reading it.
  277.  
  278.  
  279.                                     Legal Stuff
  280.                                     
  281. If you like it, let me know.  If you use it, send me money - please.  If there are bugs, tell
  282. me, I may actually fix them.  Every effort has been made to ensure that this software
  283. works as specified, but it has no warranties, expressed or implied, as to its usefulness, 
  284. stability, or functionalty.  Use this software at your own risk.
  285.  
  286. You may use applications made with a registered File Dropper for your personal use at no
  287. additional charge, but for commercial use, you must aquire a site license from me.  Contact
  288. me at one of the above addresses to find out about the site licenses. Anyone
  289. wishing to distribute an application using File Dropper along with any commercial
  290. or shareware software package, or as a commercial or shareware application, in house or out,
  291. may do so only with my expressed written consent.
  292.  
  293. If you receive the source code to File Dropper, you may modify it and use it in your own projects
  294. and distribute them as long as they are free of any charge, my name is displayed in the About
  295. Box or other equally accessable place, and are used for only non-commercial use.  If the application 
  296. you are distributing is a File Dropper type application, you must either leave the "About YourAppName..." 
  297. menu item and functionality in place, although you can change the menu item's name to be more appropriate, 
  298. or give me credit in your custom about box, including "This application is based on File 
  299. Dropper by Troy Anderson" and "File Dropper © 1996 Troy Anderson".
  300.